outdent

What is outdent?

The 'outdent' npm package is a utility for removing leading indentation from multiline strings. It helps in maintaining clean and readable code by allowing developers to write multiline strings without worrying about the indentation affecting the string content.

What are outdent's main functionalities?

Basic Usage

This feature allows you to remove leading indentation from a multiline string. The `outdent` function is used as a tagged template literal to process the string and remove any leading spaces.

const outdent = require('outdent');
const text = outdent`
  This is a multiline string.
  The indentation will be removed.
`;
console.log(text);

Custom Indentation

This feature allows you to customize the behavior of the outdent function. In this example, the `trimLeadingNewline` option is set to `false`, so the leading newline is preserved.

const outdent = require('outdent');
const text = outdent({ trimLeadingNewline: false })`
  This is a multiline string.
  The first line's indentation will be preserved.
`;
console.log(text);

Nested Templates

This feature demonstrates how you can use nested templates with the outdent function. The nested template's indentation is also removed, ensuring consistent formatting.

const outdent = require('outdent');
const nested = outdent`
  Nested template
  with indentation.
`;
const text = outdent`
  This is a multiline string.
  ${nested}
  The indentation will be removed.
`;
console.log(text);

Other packages similar to outdent

dedent

The 'dedent' package is similar to 'outdent' in that it also removes leading indentation from multiline strings. However, 'dedent' is simpler and does not offer as many customization options as 'outdent'.

strip-indent

The 'strip-indent' package removes the leading indentation from each line in a string. It is similar to 'outdent' but focuses solely on removing indentation without additional customization options.

common-tags

The 'common-tags' package provides a collection of template literal tags, including one for removing indentation. It offers more functionality beyond just outdenting, such as HTML escaping and trimming whitespace.

README

outdent

Removes leading indentation from ES6 template strings

ES6 template strings are great, but they preserve everything between the backticks, including leading spaces. Sometimes I want to indent my template literals to make my code more readable without including all those spaces in the string.

Outdent will remove those leading spaces, as well as the leading and trailing newlines.

Usage

Import outdent using your module system of choice.

// Deno
import outdent from 'http://deno.land/x/outdent/mod.ts';
// ECMAScript modules
import outdent from 'outdent';
// CommonJS
const outdent = require('outdent');

Examples

import outdent from 'outdent';

const markdown = outdent`
    # My Markdown File

    Here is some indented code:

        console.log("hello world!");
`;

console.log(markdown);

fs.writeFileSync('output.md', markdown);

The contents of output.md do not have the leading indentation:

# My Markdown File

Here is some indented code:

    console.log("hello world!");

As a JavaScript string:

var markdown = '# My Markdown File\n' +
               '\n' +
               'Here is some indented code:\n' +
               '\n' +
               '    console.log("hello world!");';

You can pass options to outdent to control its behavior. They are explained in Options.

const output = outdent({trimLeadingNewline: false, trimTrailingNewline: false})`
    Hello world!
`;

assert(output === '\nHello world!\n');

You can explicitly specify the indentation level by passing outdent as the first interpolated value. Its position sets the indentation level and it is removed from the output:

const output = outdent`
      ${outdent}
        Yo
    12345
          Hello world
`;

assert(output === '  Yo\n345\n    Hello world');

Note: ${outdent} must be alone on its own line without anything before or after it. It cannot be preceded by any non-whitespace characters. If these conditions are not met, outdent will follow normal indentation-detection behavior.

Outdent can also remove indentation from plain strings via the string method.

const output = outdent.string('\n    Hello world!\n');

assert(output === 'Hello world!');

Options

trimLeadingNewline

Default: true

trimTrailingNewline

Default: true

Whether or not outdent should remove the leading and/or trailing newline from your template string. For example:

var s = outdent({trimLeadingNewline: false})`
    Hello
`;

assert(s === '\nHello');

s = outdent({trimTrailingNewline: false})`
    Hello
`

assert(s === 'Hello\n');

s = outdent({trimLeadingNewline: false, trimTrailingNewline: false})`

`;

assert(s === '\n\n');

newline

Default: null

If set to a string, normalize all newlines in the template literal to this value.

If null, newlines are left untouched.

s = outdent({newline: '\r\n'}) `
    first
    second
`;

assert(s === 'first\r\nsecond');

Newlines that get normalized are '\r\n', '\r', and '\n'.

Newlines within interpolated values are never normalized.

Although intended for normalizing to '\r\n', you can use any string, for example a space.

const s = outdent({newline: ' '}) `
    Hello
    world!
`;

assert(s === 'Hello world!');

Gotchas

Start on a new line

Start the contents of your template string on a new line after the opening backtick. Otherwise, outdent has no choice but to detect indentation from the second line, which does not work in all situations.

// Bad
const output = outdent `* item 1
                          * sub-item
`;
// output === '* item 1\n* sub-item'; Indentation of sub-item is lost

// Good
const output = outdent `
    * item 1
      * sub-item
`;

Spaces and tabs

Spaces and tabs are treated identically. outdent does not verify that you are using spaces or tabs consistently; they are all treated as a single character for the purpose of removing indentation. Spaces, tabs, and smart tabs should all work correctly provided you use them consistently.

TypeScript declarations

This module includes TypeScript type declarations so you will get code completion and error-checking without installing anything else.

Questions or Bugs?

File an issue on Github: https://github.com/cspotcode/outdent/issues